home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
CICA 1995 August
/
CICA - The Ultimate Collection of Shareware for Windows (Disc 2) (August 1995).iso
/
disc2
/
demo
/
gcp_24.exe
/
GCP.H_
/
GCP.H
Wrap
C/C++ Source or Header
|
1994-04-07
|
15KB
|
370 lines
/*
* Dart Communications
* 1 April 94 for rel 2.4.2
*/
/* NOTES for rel 2.4.2...important if you are upgrading from an older version
Dart Communications continues to refine this interface definition, GCP.H, to provide
the most explicit and simple interface as possible. We regret if any of these
changes cause problems as you upgrade to this version, but out technical support
staff stands ready to answer any questions you may have.
The following summarizes this upgrade from version 2.3 to 2.4.2
1. The HAGENT type has been replaced with the HGCP_SESSION type. This change makes
GCP more standard with other other interface definitions (such as Win SNMP).
Just replace HAGENT with HGCP_SESSION.
2. The GCP_ERROR codes have dropped the "E" out of the name and some have been
modified or added.
3. GCP_CLOSE and GCP_ABORT commands have been separated out as a new function,
GCPclose(). This makes GCPclose() the reciprocal of GCPopen(), which is more
standard with other interface definitions. GCP_CLOSED has replaced GCP_CLOSE,
to be consistent with GCP_OPENED.
4. GCP_OPEN_PARAMS has been deleted from the interface, and GCPopen() has been
changed to take these parameters explicitly.
5. There was a little confusion as to how the GCP_MANUALCLOSE, GCP_AUTOCLOSE, and
GCP_RELEASE commands worked. We have dropped these from the interface, and
now rely on the simple GCP_HIDE and GCP_SHOW messages. Calling GCP_SHOW always
shows the GCP server as an icon, and starts the server if it is not running.
Calling GCP_HIDE hides the server, and terminates its execution if no Sessions
are active. Just use GCP_HIDE to ensure you have released the server and
GCP_SHOW to view it for debugging purposes.
6. The HGCP_SESSION is no longer a value starting at 1 and increasing for each
session created. Consequently there is now no "ownership" problem, where a "bad"
program could control your session. Since HGCP_SESSION is now virtually
random, it has been dropped out of the GCPdispatch() function as a parameter.
Just don't use it there anymore.
7. In some places (like Params.Buffer.pAddress), the pointer reference has been
replaced with an array reference (like Params.Buffer.RemoteAddress[24]).
This change has simplified usage of the interface, and helps cut-down
on run-time errors (uninitialized pointers). Just copy your address into
the array. The only place pointers are still used are in the
Params.Buffer.Ptr element. This is absolutely necessary, as it may be of
any size.
8. GCPcommand() has been replaced by GCPdispatch(), a name-only change that provides
consistency with the "dispatch" concept seen in windows and X-11 systems.
9. Last, and most important, GCP_API.DLL and GCP.EXE are now tagged with version
numbers, ala GCP242C.DLL and GCP242.EXE. This mechanism will ensure that
no conflicts arise when different GCP versions are being used to support
different applications.
The convention now will be that GCPxxxC.DLL will be frozen at each major revision
number 'xxx', so that customers will be assured that once they link to GCPxxxC.LIB,
their app will always look for GCPxxxC.DLL (the 'C' is for client). There
will always be a matching GCPxxx.EXE for the DLL. We do not, however,
guarantee that over the life of a single xxx version, the interface between
the DLL and EXE halves will remain the same. Therefore, you can assume that
any GCPxxC.DLL / GCPxx.EXE pair (distributed together) will work together, and
it is also safe to replace any pair with newer minor revisions as long as
the xxx matches (without re-compiling). When a major revision occurs (xxx changes
and the GCP.H file changes), recompilation will be necessary.
Going to all this trouble will ensure that developers X and Y, using different
version of GCP++, will coexist without difficulties.
*/
#ifndef GCP_H
#define GCP_H
/*
* This file defines the interface to the GCP Server, GCP.DLL.
* Section 1. Structures and enums.
* Section 2. Function prototypes.
*/
/***************************************************************************
****************************************************************************
Section 1. Structures and enums
****************************************************************************
***************************************************************************/
/* error codes returned by API functions or included in GCP_STATUS */
typedef enum {
GCP_OK=0, /* OK return */
GCP_UNKNOWN=600, /* An error of unknown origin has occurred */
GCP_NOWINSOCK, /* WINSOCK.DLL not located on system */
GCP_ZEROCNT, /* buffer of zero count has been presented */
GCP_RESERVED3, /* reserved */
GCP_RESERVED4, /* reserved */
GCP_RESERVED5, /* reserved */
GCP_RESERVED6, /* reserved */
GCP_RESERVED7, /* reserved */
GCP_NOGCPMEM, /* GCP Server cannot be started due to insufficient memory */
GCP_RDOS, /* There was a DOS error on the remote workstation */
GCP_DOS, /* There was a DOS error on the local workstation */
GCP_RNOENT, /* remote file not found */
GCP_NOENT, /* local file not found */
GCP_NOMEM, /* Insufficient resources - object not created */
GCP_NETWORK, /* Unspecified network error */
GCP_ALREADYOPEN, /* Daemon was previously opened on specified socket */
GCP_BADSESSION, /* Session handle is not known */
GCP_BADSESSIONTYPE, /* Session type not supported */
GCP_BADCALLBACK, /* Callback window does not exist */
GCP_EOF, /* end of file reached */
GCP_BADMSG, /* Msg Request Not Supported by Function/Session */
GCP_RCLOSE, /* Remote party has closed connection or hung up phone */
GCP_NOGCP, /* GCP Server is not running and cannot be found */
GCP_BADNAME, /* host name given is unknown */
GCP_BADVERSION, /* GCP Server and GCP.DLL versions do not match */
GCP_NOLICENSE, /* DLL interface is not licensed for distribution */
GCP_BUSY, /* GCP Server cannot get processor to clear messages */
GCP_CONNREFUSED, /* host reached, but connection refused (not listening?) */
GCP_ELAST
} GCP_ERROR;
/* messages to be handled */
#define GCP_BASE 2000
typedef enum
{
GCP_OPENED=GCP_BASE, /* session has been opened successfully or failed with error */
GCP_CLOSED, /* session was closed */
GCP_RESERVED, /* reserved for later use */
GCP_SEND, /* send a buffer or confirms a buffer was sent */
GCP_RECV, /* a buffer has been received */
GCP_PUT_TFTP_FILE, /* send a file or confirms that a file was sent */
GCP_GET_TFTP_FILE, /* get a file or confirms that a file was received */
GCP_TELNET, /* for negotiating Telnet host options and commands */
GCP_SHOW, /* show the GCP Server as an icon */
GCP_HIDE, /* hide the display of the GCP Server (default) */
GCP_SEND_DATAGRAM, /* parameters include destination address and port */
GCP_RECV_DATAGRAM, /* parameters include source address and port */
GCP_LAST /* place-holder */
} GCP_COMMAND;
DECLARE_HANDLE (HGCP_SESSION); /* used to reference created Sessions */
typedef enum /* currently supported sessions and daemons */
{
UDP_SESSION=GCP_BASE+100, /* a UDP sessions handles send/recv of datagrams */
TCP_SESSION, /* a TCP session provides buffered streams */
TCP_DAEMON, /* will spawn a TCP_SESSION when connected to */
TELNET_SESSION, /* a TELNET session provides buffered streams and option neg */
TELNET_DAEMON, /* will spawn a TELNET_SESSION when connected to */
TFTP_SESSION, /* will send/recv files to/from any TFTP server */
TFTP_DAEMON /* will serve files to/from any TFTP client */
} GCP_SESSION_TYPE;
/***************************************************************************
this section includes descriptions for the GCPdispatch function parameters
***************************************************************************/
/* for convenience, make a define for (const BYTE far *) */
typedef const BYTE far * LPCBYTE;
/* following typedef from MSVC */
#ifndef _SIZE_T_DEFINED
typedef unsigned int size_t;
#define _SIZE_T_DEFINED
#endif
typedef struct
{
LPCBYTE Ptr; /* pointer to buffer for reading only */
size_t Cnt; /* byte count in buffer */
unsigned long CommandInstance; /* user data */
char RemoteAddress[24]; /* remote name or address for UDP sessions only */
unsigned short RemotePort; /* remote port for UDP sessions only */
} GCP_BUFFER_PARAMS;
typedef enum
{
NETASCII,
OCTET } TFTP_MODE; /* transfer mode for TFTP sessions */
typedef struct
{
char LocalFileSpec[64]; /* local filespec or name */
char RemoteFileSpec[64]; /* remote filespec of name */
unsigned long CommandInstance; /* user data */
char RemoteAddress[24]; /* remote address (dot notation or name) for TFTP sessions only */
TFTP_MODE Mode;
} GCP_TFTP_PARAMS;
#define GO_AHEAD_CMD 249
#define WILL_CMD 251
#define WONT_CMD 252
#define DO_CMD 253
#define DONT_CMD 254
#define SB_CMD 250 /* suboption negotiation */
typedef struct
{
BYTE Cmd; /* option command WILL_CMD, WONT_CMD, DO_CMD, DONT_CMD */
BYTE Option; /* TELNET option to be negotiated */
BYTE SubOption[256]; /* TELNET suboption string (if applicable) */
size_t SubOptionCnt; /* length of suboption control sequence */
} GCP_TELNET_PARAMS;
#define ECHO_OPTION 1 /* the ECHO option is popular */
typedef union /* currently supported request types */
{
GCP_BUFFER_PARAMS Buffer; /* Params for GCP_SEND and GCP_SEND_DATAGRAM */
GCP_TFTP_PARAMS Tftp; /* Params for GCP_TFTP_PUT_FILE and GCP_TFTP_GET_FILE */
GCP_TELNET_PARAMS Telnet; /* Params for GCP_TFTP */
} GCP_COMMAND_PARAMS;
/***************************************************************************
this section includes descriptions for the GCPquery function parameters
***************************************************************************/
typedef enum
{
GCP_GET_LOCAL_HOST=GCP_BASE+300, /* gets local host from the host table */
GCP_GET_FIRST_HOST, /* gets first remote host from the host table */
GCP_GET_NEXT_HOST, /* gets next remote host from the host table */
GCP_GET_STATUS, /* lParam is pointer to session Status structure */
} GCP_QUERY;
typedef struct /* definition of host structure */
{
char Name[64]; /* official name of host (null terminated) */
char Addr[16]; /* net address in dot notation (null terminated) */
} HOST;
typedef HOST far * LPHOST;
typedef struct /* describes statistics available to user */
{
unsigned long StartTime, /* seconds since 1 Jan 1970 */
StopTime, /* seconds since 1 Jan 1970 */
InCnt, /* file or buffer bytes transferred in over session */
OutCnt, /* file or buffer bytes transferred out over session */
InRate,
OutRate; /* bytes/sec */
} GCP_STATISTICS;
typedef struct
{
HGCP_SESSION hSession; /* identification of Session */
GCP_SESSION_TYPE SessionType; /* identification of Session type */
unsigned long OpenInstance; /* instance from GCPopen() */
GCP_COMMAND_PARAMS Params; /* parameters specific to GCP_COMMAND received */
GCP_STATISTICS Stats; /* statistics structure */
GCP_ERROR Error; /* Error code, if any */
GCP_COMMAND Reserved; /* reserved for internal use */
} GCP_STATUS;
typedef GCP_STATUS far *LPGCP_STATUS;
typedef union
{
HOST Host;
GCP_STATUS Status;
} GCP_QUERY_RESULTS;
/***************************************************************************
****************************************************************************
Section 2. Function prototypes
****************************************************************************
***************************************************************************/
#ifdef __cplusplus
extern "C"
{
#endif
/*
GCPopen() establishes a Session or Daemon for the client applications
Success/failure is confirmed via a GCP_OPENED callback message
An error returned indicates an invalid parameter
*/
GCP_ERROR far pascal _export GCPopen
(
GCP_SESSION_TYPE Type, /* type of Session being used */
HWND hCallbackWnd, /* callback window handle */
WORD CallbackMsg, /* callback window message */
unsigned long OpenInstance, /* instance specific data for app */
const char far *pAddress, /* address in dot notation or name from host table */
unsigned short Port /* local (passive connect) or remote (active connect) port */
);
/*
GCPdispatch() commands the GCP server to perform an action
Success/failure is confirmed via a callback message
An error returned indicates an invalid parameter
*/
GCP_ERROR far pascal _export GCPdispatch
(
HGCP_SESSION hSession, /* identification of Session, if applicable */
GCP_COMMAND Command, /* Command */
GCP_COMMAND_PARAMS far *pParams /* parameters specific to Command, if applicable */
);
/*
GCPclose() closes a Session or Daemon, releasing system resources
Success/failure is confirmed via a GCP_CLOSED callback message
An error returned indicates an invalid parameter
*/
GCP_ERROR far pascal _export GCPclose
(
HGCP_SESSION hSession, /* identification of Session or Daemon to close */
BOOL Abort /* specify TRUE to immediately release unsent buffers, files */
/* use FALSE to finish gracefully before closing */
);
/*
GCPquery() queries the GCP server synchronously
An error returned indicates an invalid parameter
For TCP_SESSION's, the GCP_GET_STATUS msg causes the server to poll for received data
and to attempt to send buffered data
*/
GCP_ERROR far pascal _export GCPquery
(
HGCP_SESSION hSession, /* identification of Session, if applicable */
GCP_QUERY Msg, /* identification of utility function */
GCP_QUERY_RESULTS far *pResults /* parameters for the function */
);
/*
GCPalloc() duplicates a GCP_STATUS structure, including large buffers referenced
An NULL returned indicates an allocation failure
This is useful upon receipt of a callback message, where the client must save a
copy of the GCP_STATUS structure for later processing
*/
LPARAM far pascal _export GCPalloc
(
WPARAM Msg, /* */
LPARAM pStatus /* makes copy of GCP_STATUS structure and data */
);
/*
GCPfree() frees the GCP_STATUS struction allocated by GCPalloc()
*/
BOOL far pascal _export GCPfree
(
LPARAM pStatus
);
/*
GCPferror () provides a textual description of the error for presentation
*/
LPSTR far pascal _export GCPperror
(
GCP_ERROR Error /* error code from GCP server */
);
#ifdef __cplusplus
}
#endif
#endif